IMoniker - File Moniker Implementation
File monikers
are monikers that represent a path in the file system; a file moniker can
identify any object that is saved in its own file. To identify objects
contained within a file, you can compose monikers of other classes (for
example, item monikers) to the right of a file moniker. However, the moniker to
the left of a file moniker within a composite must be another file moniker, an
anti-moniker, or a class moniker. It is illegal, for example, for an item
moniker to appear to the left of a file moniker in a composite.
Note that an
anti-moniker is the inverse of an entire file moniker, not the inverse of a
component of the path that the moniker represents; that is, when you compose an
anti-moniker to the right of a file moniker, the entire file moniker is
removed. If you want to remove just the rightmost component of the path
represented by a file moniker, you must create a separate file moniker based on
the .. path and then compose that to the end of the file moniker.
When to Use
If you re a
moniker client (that is, you re using a moniker to get an interface pointer to
an object), you typically don t need to know the class of the moniker you re
using; you simply call methods using an IMoniker interface pointer.
If you re a
moniker provider (that is, you re handing out monikers that identify your
objects to make them accessible to moniker clients), you must use file monikers
if the objects you re identifying are stored in files. If each object resides
in its own file, file monikers are the only type you need. If the objects
you re identifying are smaller than a file, you need to use another type of
moniker (for example, item monikers) in addition to file monikers.
To use file
monikers, you must use the CreateFileMonikerD4G1EE function to create the monikers. In order
to allow your objects to be loaded when a file moniker is bound, your objects
must implement the IPersistFile interface.
The most
common example of moniker providers are OLE server applications that support
linking. If your OLE server application supports linking only to file-based
documents in their entirety, file monikers are the only type of moniker you need.
If your OLE server application supports linking to objects smaller than a
document (such as sections of a document or embedded objects), you must use
item monikers as well as file monikers.
Remarks
IMoniker::BindToObject
When pmkToLeft
is NULL, the method looks for the moniker in the ROT, and if found, queries the
retrieved object for the requested interface pointer. If the moniker is not
found in the ROT, the method loads the object from the file system and
retrieves the requested interface pointer.
If pmkLeft
is not NULL, then instead of determining the class to instantiate and
initialize with the contents of the file referred to by the file moniker using GetClassFile
(or other means), call pmkLeft->BindToObject for IClassFactory and IClassActivator, retrieve this pointer in pcf.
If this fails
with E_NOINTERFACE, return MK_E_INTERMEDIATEINTERFACENOTSUPPORTED.
If the IClassFactory
pointer is successfully retrieved, call
pcf->CreateInstance(IID_IPersistFile, (void**)&ppf) to get a fresh instance
of the class to be initialized and initialize it using IPersistFile or
other appropriate means per the existing initialization paths of File moniker.
IMoniker::BindToStorage
This method
opens the file specified by the path represented by the moniker and returns an IStorage pointer to that file. The
method supports binding to IStorage interface only; if IStream or ILockBytes is requested in riid,
the method returns E_UNSPEC, and if other interfaces are requested, this method
returns E_NOINTERFACE. IStream and ILockBytes will be supported
in future releases. Unless pmkToLeft is a class moniker, pmkToLeft
should be NULL, as in the implementation of IMoniker::BindToObject. For
situations where pmkToLeft is non-NULL, see the above description.
IMoniker::Reduce
This method
returns MK_S_REDUCED_TO_SELF and passes back the same moniker.
IMoniker::ComposeWith
If pmkRight
is an anti-moniker, the returned moniker is NULL. If pmkRight is a
composite whose leftmost component is an anti-moniker, the returned moniker is
the composite with the leftmost anti-moniker removed. If pmkRight is a
file moniker, this method collapses the two monikers into a single file
moniker, if possible. If not possible (e.g., if both file monikers represent
absolute paths, as in d:\work and e:\reports), then the returned
moniker is NULL and the return value is MK_E_SYNTAX. If pmkRight is
neither an anti-moniker nor a file moniker, then the method checks the fOnlyIfNotGeneric
parameter; if it is FALSE, the method combines the two monikers into a generic
composite; if it is TRUE, the method sets *ppmkComposite to NULL and
returns MK_E_NEEDGENERIC.
IMoniker::Enum
This method
returns S_OK and sets ppenumMoniker to NULL.
IMoniker::IsEqual
This method
returns S_OK if *pmkOther is a file moniker and the paths for both
monikers are identical (using a case-insensitive comparison). Otherwise, the
method returns S_FALSE.
IMoniker::Hash
This method
calculates a hash value for the moniker.
IMoniker::IsRunning
If pmkNewlyRunning
is non-NULL, this method returns TRUE if that moniker is equal to this moniker.
Otherwise, the method asks the ROT whether this moniker is running. The method
ignores pmkToLeft.
IMoniker::GetTimeOfLastChange
If this
moniker is in the ROT, this method returns the last change time registered
there; otherwise, it returns the last write time for the file. If the file
cannot be found, this method returns MK_E_NOOBJECT.
IMoniker::Inverse
This method
returns an anti-moniker (i.e., the results of calling CreateAntiMoniker).
IMoniker::CommonPrefixWith
If both
monikers are file monikers, this method returns a file moniker that is based on
the common components at the beginning of two file monikers. Components of a
file moniker can be:
A machine name of the form \\server\share.
A machine name is treated as a single component, so two monikers representing
the paths \\myserver\public\work and \\myserver\private\games do not have
\\myserver as a common prefix.
A drive designation (for example, C: ).
A directory or file name.
If the other
moniker is not a file moniker, this method passes both monikers in a call to
the MonikerCommonPrefixWith
function. This function correctly handles the case where the other moniker is a
generic composite.
This method
returns MK_E_NOPREFIX if there is no common prefix.
IMoniker::RelativePathTo
This method
computes a moniker which when composed to the right of this moniker yields the
other moniker. For example, if the path of this moniker is
C:\work\docs\report.doc and if the other moniker is
C:\work\art\picture.bmp, then the path of the computed moniker would be
..\..\art\picture.bmp.
IMoniker::GetDisplayName
This method
returns the path that the moniker represents. If this method is called by a
16-bit application, the method checks to see whether the specified file exists
and, if so, returns a short name for that file because 16-bit applications are
not equipped to handle long file names.
IMoniker::ParseDisplayName
This method
tries to acquire an IParseDisplayName pointer, first by binding to the class factory
for the object identified by the moniker, and then by binding to the object
itself. If either of these binding operations is successful, the file moniker
passes the unparsed portion of the display name to the IParseDisplayName::ParseDisplayName method.
This method
returns MK_E_SYNTAX if pmkToLeft is non-NULL.
IMoniker::IsSystemMoniker
This method returns
S_OK, and passes back MKSYS_FILEMONIKER.
See Also